#ifndef __VM_SENSOR
#define __VM_SENSOR

#include "vmsys.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @return value of VRE sensor interfaces
 * @{
 */
 /**
  * succeed
  */
#define SENSOR_OP_SUCCESS									(0)
/**
 * asynchrous operation
 */
#define SENSOR_OP_ASYNCHROUS								(1)
/**
 * invalid paramters
 */
#define SENSOR_ECODE_BAD_PARAM							(-1)
/**
 * unsupported operation
 */
#define SENSOR_ECODE_UNSUPPORT_OPERATION				(-2)
/**
 * unsupported operation in current state
 */
#define SENSOR_ECODE_UNSUPPORT_OPERATION_IN_STATUS   	(-3)
/**
 * invalid sensor handle
 */
#define SENSOR_ECODE_INVALID_HANDLE						(-4)
/**
 * invalid sensor name
 */
#define SENSOR_ECODE_INVALID_NAME						(-5)
/**
 * sensor instance exists
 */
#define SENSOR_ECODE_INSTANCE_CREATED					(-6)
/**
 * no registered callback function
 */
#define SENSOR_ECODE_NOT_REG_NOTIFY						(-7)
/**
 * insufficent memory
 */
#define SENSOR_ECODE_NO_MEMORY							(-8)
/** @} */

/**
 * sensor callback message
 */
typedef enum {
	SENSOR_START_DONE, 			/**<succeed to start sensor	*/
	SENSOR_START_ABORT, 			/**<fail to start sensor	*/
	SENSOR_STOP_DONE,				/**<succeed to stop sensor 	*/
	SENSOR_STOP_ABORT,			/**<fail to stop sensor 		*/
	SENSOR_SET_OPTION_DONE, 		/**<succeed to set sensor property	*/
	SENSOR_SET_OPTION_ABORT, 	/**<fail to set sensor property		*/
	SENSOER_DATA_RECEIVED		/**<get the sensor data			*/
}VM_SENSOR_MESSAGE;

/**
 * @struct callback data structure
 * @brief data structure used in callback function
 */
typedef struct vm_sensor_notify_t {
	VMINT sensor_handle;			/**<sensor handle						*/
	VM_SENSOR_MESSAGE message;	/**<message					*/
	void* sensor_data;				/**<sensor data			*/
	VMUINT data_size;				/**<length of sensor data		*/
	VMINT reserved;					/**<reserved						*/
}vm_sensor_notify_t;

typedef void (*SENSOR_NOTIFY_FUNC)(vm_sensor_notify_t* sensor_notify, void* user_data);

/**
 * create sensor instance
 *  
 * @param[in]				name 					sensor name that is unique for a device
 * @param[out]			sensor_handle the pointer to the buffer that receives the sensor handle that is valid
 *																when the return code is SENSOR_OP_SUCCESS
 *
 * @return					return value or error code
 * @retval					SENSOR_OP_SUCCESS 	-	succeed
 * @retval					SENSOR_OP_ERROR_CODE_BAD_PARAM 	-	invalid paramter (sensor_handle is NULL)
 * @retval					SENSOR_ECODE_INVALID_NAME 	- invalid sensor name
 * @retval					SENSOR_ECODE_INSTANCE_CREATED - the instance is created
 * @retval					SENSOR_ECODE_NO_MEMORY 	-	insufficient memory
 *
 * @note						the created sensor handle should be relaesed by vm_release_sensor_instance.
 * @code 
 * // vm_freescale_MMA7455L.h
 * #define USE_SENSOR_NAME "sensor:quality=acceleration;device=mobile;model=TCL-E9;location=inside"
 * #define G_SELECT "G_SELECT"
 * typedef enum {2G, 4G, 8G}G_SELECT_ENUM;
 * @endcode
 * @code
 * // sensor_sample.c
 * VMINT handle;
 * if (vm_create_sensor_instance(USE_SENSOR_NAME, &handle) == SENSOR_OP_SUCCESS)
 * {
 * 	if (vm_register_sensor_notify(handle, (RECEIVE_DATA_FUNC)receive_callback, NULL) == SENSOR_OP_SUCCESS)
 *  	{
 * 		VMINT res = vm_set_sensor_numeric_option(handle, G_SELECT, 2G);
 *		if (res == SENSOR_OP_SUCCESS)
 *		{
 *			// succeed to set sensor
 *		}
 *    		else if (res == SENSOR_OP_ASYNCHROUS)
 *		{
 *			// the sensor option will be returned in a asynchrous mode
 *		}
 *		else
 *		{
 *			// deal the exception
 *		}
 *	}
 * }
 * @endcode
 */
VMINT  vm_create_sensor_instance(const VMSTR name, VMINT* sensor_handle);

/**
 * release the sensor instance
 * 
 * @param[in]				sensor_handle 	sensor handle
 *
 * @return 				
 * @retval					SENSOR_OP_SUCCESS 	-	succeed
 * @retval					SENSOR_OP_ERROR_CODE_INVALID_HANDLE 	- invalid sensor handle
 * @retval					SENSOR_OP_ERROR_CODE_UNSUPPORT_IN_STATUS 	- the function is invalid in current stste
 *
 * @see							vm_create_sensor_instance 
 */
VMINT vm_release_sensor_instance(VMINT sensor_handle);

/**
 * register the sensor callback
 * 
 * @param[in]				sensor_handle 	sensor handle
 * @param[in]				callback 				callback function
 * @param[in]				user_data 			user data. It is sent as paramter when callback function is invoked.
 * @return					return value or error code
 * @retval					SENSOR_OP_SUCCESS 	-	succeed
 * @retval					SENSOR_OP_ERROR_CODE_BAD_PARAM 	-	invalid paramter
 * @retval					SENSOR_OP_ERROR_CODE_INVALID_HANDLE 	- invalid sensor handle
 * 
 */
VMINT vm_register_sensor_notify(VMINT sensor_handle, SENSOR_NOTIFY_FUNC callback, void* user_data);

/**
 * set sensor value type (numeric)
 * 
 * @param[in]				sensor_handle 	sensor handle
 * @param[in]				control_name 		sensor option name
 * @param[in]				value 					sensor option value
 * @return					return value or error code
 * @retval					SENSOR_OP_SUCCESS 	-	succeed
 * @retval					SENSOR_OP_ASYNCHROUS  -	the function is asynchrous operation. If the operation succeed,
 * 																					the callback receives SENSOR_SET_OPTION_DONE. Or the callback 
 *																					receives SENSOR_SET_OPTION_ABORT.
 * @retval					SENSOR_ECODE_UNSUPPORT_OPERATION_IN_STATUS 	- the operation invalid in current state
 * @retval					SENSOR_OP_ERROR_CODE_INVALID_HANDLE 	- invalid sensor handle
 * @retval					SENSOR_OP_ERROR_CODE_BAD_PARAM 	-	invalid paramter (control_name is NULL)
 * @retval					SENSOR_ECODE_NOT_REG_NOTIFY 	-	no callback function that registered by 
 *																									vm_register_sensor_notify
 * @see					vm_set_sensor_string_option
 */
VMINT vm_set_sensor_numeric_option(VMINT sensor_handle, const VMSTR control_name, 
	VMINT value);

/**
 * set sensor value type (string)
 * 
 * @param[in]				sensor_handle 	sensor handle
 * @param[in]				control_name 		sensor option name
 * @param[in]				value 					sensor option value
 * @return					return value or error code
 * @retval					SENSOR_OP_SUCCESS 	-	succeed
 * @retval					SENSOR_OP_ASYNCHROUS  -	the function is asynchrous operation. If the operation succeed,
 * 																					the callback receives SENSOR_SET_OPTION_DONE. Or the callback 
 *																					receives SENSOR_SET_OPTION_ABORT.
 * @retval					SENSOR_ECODE_UNSUPPORT_OPERATION_IN_STATUS 	- the operation invalid in current state
 * @retval					SENSOR_OP_ERROR_CODE_INVALID_HANDLE 	- invalid sensor handle
 * @retval					SENSOR_OP_ERROR_CODE_BAD_PARAM 	-	invalid paramter (control_name is NULL)
 * @retval					SENSOR_ECODE_NOT_REG_NOTIFY 	-	no callback function that registered by 
 *																									vm_register_sensor_notify
 * @see					vm_set_sensor_string_option
 */
VMINT vm_set_sensor_string_option(VMINT sensor_handle, const VMSTR control_name, 
	VMSTR value);

/**
 * start sensor
 * 
 * @param[in]				sensor_handle 	sensor handle
 *
 * @return					return value or error code
 * @retval					SENSOR_OP_SUCCESS 	-	succeed
 * @retval					SENSOR_OP_ASYNCHROUS  -	the function is asynchrous operation. If the operation succeed,
 * 																					the callback receives SENSOR_SET_OPTION_DONE. Or the callback 
 *																					receives SENSOR_SET_OPTION_ABORT.
 * @retval					SENSOR_ECODE_UNSUPPORT_OPERATION_IN_STATUS 	- the operation invalid in current state
 * @retval					SENSOR_OP_ERROR_CODE_INVALID_HANDLE 	- invalid sensor handle
 * @retval					SENSOR_OP_ERROR_CODE_BAD_PARAM 	-	invalid paramter
 * @retval					SENSOR_ECODE_NOT_REG_NOTIFY 	-	no callback function that registered by 
 *																									vm_register_sensor_notify
 * @note						After calling this function, user must stop the sensor by vm_stop_sensor befor calling 
 *									vm_release_sensor_instance.
 *
 * @see 					vm_stop_sensor
 */
VMINT vm_start_sensor(VMINT sensor_handle);

/**
 * stop the sensor
 * 
 * @return					return value or error code
 * @retval					SENSOR_OP_SUCCESS 	-	succeed
 * @retval					SENSOR_OP_ASYNCHROUS  -	the function is asynchrous operation. If the operation succeed,
 * 																					the callback receives SENSOR_SET_OPTION_DONE. Or the callback 
 *																					receives SENSOR_SET_OPTION_ABORT.
 * @retval					SENSOR_ECODE_UNSUPPORT_OPERATION_IN_STATUS 	- the operation invalid in current state
 * @retval					SENSOR_OP_ERROR_CODE_INVALID_HANDLE 	- invalid sensor handle
 * @retval					SENSOR_OP_ERROR_CODE_BAD_PARAM 	-	invalid paramter
 * @retval					SENSOR_ECODE_NOT_REG_NOTIFY 	-	no callback function that registered by 
 *																									vm_register_sensor_notify
 * @retval					SENSOR_ECODE_UNSUPPORT_OPERATION_IN_STATUS 	- the function is unsupported in current state
 *
 * @see					vm_start_sensor		
 */
VMINT vm_stop_sensor(VMINT sensor_handle);

#ifdef __cplusplus
}
#endif 

#endif
